<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="module-profile.html" />
<link rel="parent" href="module-profile.html" />
<link rel="next" href="profile-limits.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>25.4.1 The Stats Class </title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="25.4 reference Manual -"
  href="module-profile.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="25.4 reference Manual -"
  href="module-profile.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="25.5 Limitations"
  href="profile-limits.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-profile.html">25.4 Reference Manual -</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-profile.html">25.4 Reference Manual -</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="profile-limits.html">25.5 Limitations</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION0027410000000000000000"></a><a name="profile-stats"></a>
<br>
25.4.1 The <tt class="class">Stats</tt> Class 
</h2>

<p>
<tt class="class">Stats</tt> objects have the following methods:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5097' xml:id='l2h-5097' class="method">strip_dirs</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
This method for the <tt class="class">Stats</tt> class removes all leading path
information from file names.  It is very useful in reducing the size
of the printout to fit within (close to) 80 columns.  This method
modifies the object, and the stripped information is lost.  After
performing a strip operation, the object is considered to have its
entries in a ``random'' order, as it was just after object
initialization and loading.  If <tt class="method">strip_dirs()</tt> causes two
function names to be indistinguishable (they are on the same
line of the same filename, and have the same function name), then the
statistics for these two entries are accumulated into a single entry.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5098' xml:id='l2h-5098' class="method">add</tt></b>(</nobr></td>
  <td><var>filename</var><big>[</big><var>, ...</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This method of the <tt class="class">Stats</tt> class accumulates additional
profiling information into the current profiling object.  Its
arguments should refer to filenames created by the corresponding
version of <tt class="function">profile.run()</tt> or <tt class="function">cProfile.run()</tt>.
Statistics for identically named
(re: file, line, name) functions are automatically accumulated into
single function statistics.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5099' xml:id='l2h-5099' class="method">dump_stats</tt></b>(</nobr></td>
  <td><var>filename</var>)</td></tr></table></dt>
<dd>
Save the data loaded into the <tt class="class">Stats</tt> object to a file named
<var>filename</var>.  The file is created if it does not exist, and is
overwritten if it already exists.  This is equivalent to the method of
the same name on the <tt class="class">profile.Profile</tt> and
<tt class="class">cProfile.Profile</tt> classes.

<span class="versionnote">New in version 2.3.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5100' xml:id='l2h-5100' class="method">sort_stats</tt></b>(</nobr></td>
  <td><var>key</var><big>[</big><var>, ...</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This method modifies the <tt class="class">Stats</tt> object by sorting it according
to the supplied criteria.  The argument is typically a string
identifying the basis of a sort (example: <code>'time'</code> or
<code>'name'</code>).

<p>
When more than one key is provided, then additional keys are used as
secondary criteria when there is equality in all keys selected
before them.  For example, <code>sort_stats('name', 'file')</code> will sort
all the entries according to their function name, and resolve all ties
(identical function names) by sorting by file name.

<p>
Abbreviations can be used for any key names, as long as the
abbreviation is unambiguous.  The following are the keys currently
defined:

<p>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="left"  >Valid Arg</th>
      <th class="left"  >Meaning</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="left"   valign="baseline"><code>'calls'</code></td>
        <td class="left"  >call count</td></tr>
    <tr><td class="left"   valign="baseline"><code>'cumulative'</code></td>
        <td class="left"  >cumulative time</td></tr>
    <tr><td class="left"   valign="baseline"><code>'file'</code></td>
        <td class="left"  >file name</td></tr>
    <tr><td class="left"   valign="baseline"><code>'module'</code></td>
        <td class="left"  >file name</td></tr>
    <tr><td class="left"   valign="baseline"><code>'pcalls'</code></td>
        <td class="left"  >primitive call count</td></tr>
    <tr><td class="left"   valign="baseline"><code>'line'</code></td>
        <td class="left"  >line number</td></tr>
    <tr><td class="left"   valign="baseline"><code>'name'</code></td>
        <td class="left"  >function name</td></tr>
    <tr><td class="left"   valign="baseline"><code>'nfl'</code></td>
        <td class="left"  >name/file/line</td></tr>
    <tr><td class="left"   valign="baseline"><code>'stdname'</code></td>
        <td class="left"  >standard name</td></tr>
    <tr><td class="left"   valign="baseline"><code>'time'</code></td>
        <td class="left"  >internal time</td></tr></tbody>
</table></div>

<p>
Note that all sorts on statistics are in descending order (placing
most time consuming items first), where as name, file, and line number
searches are in ascending order (alphabetical). The subtle
distinction between <code>'nfl'</code> and <code>'stdname'</code> is that the
standard name is a sort of the name as printed, which means that the
embedded line numbers get compared in an odd way.  For example, lines
3, 20, and 40 would (if the file names were the same) appear in the
string order 20, 3 and 40.  In contrast, <code>'nfl'</code> does a numeric
compare of the line numbers.  In fact, <code>sort_stats('nfl')</code> is the
same as <code>sort_stats('name', 'file', 'line')</code>.

<p>
For backward-compatibility reasons, the numeric arguments
<code>-1</code>, <code>0</code>, <code>1</code>, and <code>2</code> are permitted.  They are
interpreted as <code>'stdname'</code>, <code>'calls'</code>, <code>'time'</code>, and
<code>'cumulative'</code> respectively.  If this old style format (numeric)
is used, only one sort key (the numeric key) will be used, and
additional arguments will be silently ignored.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5101' xml:id='l2h-5101' class="method">reverse_order</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
This method for the <tt class="class">Stats</tt> class reverses the ordering of the basic
list within the object.  Note that by default ascending vs descending order is properly selected
based on the sort key of choice.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5102' xml:id='l2h-5102' class="method">print_stats</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>restriction, ...</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This method for the <tt class="class">Stats</tt> class prints out a report as described
in the <tt class="function">profile.run()</tt> definition.

<p>
The order of the printing is based on the last <tt class="method">sort_stats()</tt>
operation done on the object (subject to caveats in <tt class="method">add()</tt> and
<tt class="method">strip_dirs()</tt>).

<p>
The arguments provided (if any) can be used to limit the list down to
the significant entries.  Initially, the list is taken to be the
complete set of profiled functions.  Each restriction is either an
integer (to select a count of lines), or a decimal fraction between
0.0 and 1.0 inclusive (to select a percentage of lines), or a regular
expression (to pattern match the standard name that is printed; as of
Python 1.5b1, this uses the Perl-style regular expression syntax
defined by the <tt class="module"><a href="module-re.html">re</a></tt> module).  If several restrictions are
provided, then they are applied sequentially.  For example:

<p>
<div class="verbatim"><pre>
print_stats(.1, 'foo:')
</pre></div>

<p>
would first limit the printing to first 10% of list, and then only
print functions that were part of filename <span class="file">.*foo:</span>.  In
contrast, the command:

<p>
<div class="verbatim"><pre>
print_stats('foo:', .1)
</pre></div>

<p>
would limit the list to all functions having file names <span class="file">.*foo:</span>,
and then proceed to only print the first 10% of them.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5103' xml:id='l2h-5103' class="method">print_callers</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>restriction, ...</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This method for the <tt class="class">Stats</tt> class prints a list of all functions
that called each function in the profiled database.  The ordering is
identical to that provided by <tt class="method">print_stats()</tt>, and the definition
of the restricting argument is also identical.  Each caller is reported on
its own line.  The format differs slightly depending on the profiler that
produced the stats:

<p>

<ul>
<li>With <tt class="module">profile</tt>, a number is shown in parentheses after each
  caller to show how many times this specific call was made.  For
  convenience, a second non-parenthesized number repeats the cumulative
  time spent in the function at the right.

<p>
</li>
<li>With <tt class="module">cProfile</tt>, each caller is preceeded by three numbers:
  the number of times this specific call was made, and the total and
  cumulative times spent in the current function while it was invoked by
  this specific caller.
</li>
</ul>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5104' xml:id='l2h-5104' class="method">print_callees</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>restriction, ...</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This method for the <tt class="class">Stats</tt> class prints a list of all function
that were called by the indicated function.  Aside from this reversal
of direction of calls (re: called vs was called by), the arguments and
ordering are identical to the <tt class="method">print_callers()</tt> method.
</dl>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="25.4 reference Manual -"
  href="module-profile.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="25.4 reference Manual -"
  href="module-profile.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="25.5 Limitations"
  href="profile-limits.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-profile.html">25.4 Reference Manual -</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-profile.html">25.4 Reference Manual -</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="profile-limits.html">25.5 Limitations</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
